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CP/M INTERFACE GUIDE 



1. INTRODUCTION 

This manual describes the CP/M system organization including 
the structure of memory, as well as system entry points. The 
intention here is to provide the necessary information required 
to write programs which operate under CP/M, and which use the 
peripheral and disk I/O facilities of the system. 

1.1 CP/M Organization 

CP/M is logically divided into four parts: 

BIOS - the basic l/O system for serial peripheral control 

BDOS - the basic disk operating system primitives 

CCP - the console command processer 

TPA - the transient program area 



The BIOS and BDOS are combined into a single program with a com- 
mon en^ry point and referred to as the FDOS. The CCP is a dis- 
tinct program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the diskette. 
The TPA is an area of memory (i.e, the portion which is not used 
by the FDOS and CCP) where various non-resident operating system 
commands are executed. User programs also execute in the TPA. 
The Qrganization of memory in a standard CP/M system is shown in 
Figure 1. 

The lower portion of memory is reserved for system information 
(which is detailed in later sections) , including user defined inter 
rupt locations. The portion between tbase and cbase is reserved 
for the transient operating system commands, while the portion 
above cbase contains the resident CCP and FDOS. The last three 
locations of memory contain a jump instruction to the FDOS entry 
point which provides access to system functions. 



1.2 Operation of Transient Programs 



Transient programs (system functions and user-defined programs) 
are loaded into the TPA and executed as follows. The operator 
communicates with the CCP by typing command lines following each 
prompt character. Each command line takes one of the forms: 

■<con»ana> 

<command> <filename> 
<command> <f ilename-^ ,<f ile type> 



Figure 1. CP/M Memory Organization 



fbase 



cbase: 



tbase : 



boot : 



FDOS 



CCP 



TPA 



System Parameters 



•address field of jump is fbase 



entry: ^® principal entry point to FDOS is at location 0005 
which contains a JMP to fbase. The address field at 
location 0006 can be used to determine the size of 
available memory, assuming the CCP is being overlayed. 



Note: The exact addresses for boot, tbase, cbase, fbase, 
and entry vary with the CP/M version (see 
Section 6. for version correspondence). 
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Where <coinmand> is either a built-in command (e.g., DIR or TYPE), 
or the name of a transient command or program. If the <command> 
is a built-in function of CP/M, it is executed immediately; other- 
wise the CCP searches the currently addressed disk for a file 
by the name 

< command > .COM 

If the file is found, it is assumed to be a memory image of a 
program which executes in the TPA, and thus implicitly originates 
at tbase in memory (see the CP/M LOAD command) . The CCP loads 
the COM file from the diskette into memory starting at tbase, 
and extending up to address cbase. 

If the <command> is followed by either a <filename> or 
<f ilename>. <f iletype> , then the CCP prepares a file control- 
block (FCB) in the system information area of memory. This FCB 
is in the form required to access the file through the FDOS, and 
is given in detail in Section 3.2. 

The program then executes, perhaps using the I/O facilities 
of the FDOS. If the program uses no FDOS facilities, then the 
entire remaining memory area is available for data used by the 
programs. If the FDOS is to remain in memory, then the transient 
program can use only up to location fbase as data.* In any case, 
if the CCP area is used by the transient, the entire CP/M system 
must be reloaded upon the transient's completion. This system 
reload is accomplished by a direct branch to location "boot" in 
memory. 

The transient uses the CP/M I/O facilities to communicate 
with,. the operator's console and peripheral devices, including 
the floppy disk subsystem. The I/O system is accessed by passing 
a "function number" and an "information address" to CP/M through 
the address marked "entry" in Figure 1. In the case of a disk 
read, for example, the transient program sends the number corres- 
ponding to a disk read, along with the address of an FCB, and 
CP/M performs the operation, returning with either a disk read 
complete indication or an error number indicating that the disk 
operation was unsuccessful. The function numbers and error in- 
dicators are given in detail in Section 3.3. 

1.3 Operating System Facilities 

CP/M facilities which are available to transients are divided 
into two categories : BIOS operations , and BDOS primitives . The 
BIOS operations are listed first:** 

* Address "entry" contains a jump to the lowest address in the 
FDOS, and thus "entry+1" contains the first FDOS address which 
cannot be overlayed. 

**The device support (exclusive of the disk subsystem) corres- 
ponds exactly to Intel's peripheral definition, including I/O 
port assignment and status byte format (see the Intel manual 

which discusses the Intel! ec MDS hardware environment) . 
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Read Console Character 
Write Console Character 
Read Reader Character 
Write Punch Character 
Write List Device Character 
Set I/O Status 
Interrogate Device Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Status 

The exact details of BIOS access are given in Section 2. The BDOS 
primitives include the following operations: 

Disk System Reset 
Drive Select 
File Creation 
File Open 
File Close 
Directory Search 
File Delete 
File Rename 
Read Record 
Write Record 

Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 

The details of BDOS access are given in Section 3. 



2. BASIC I/O FACILITIES 

Access to common peripherals is accomplished by passing a 
function number and information address to the BIOS, In general, 
the function number is passed in Register C, while the informa- 
tion address is passed in Register pair D,E. Note that this 
conforms to the PL/M Conventions for parameter passing, and thus 
the following PL/M procedure is sufficient to link to the BIOS 
when a value is returned: 

DECLARE ENTRY LITERALLY '0005H'; /* MONITOR ENTRY */ 

M0N2: PROCEDURE (FUNC, INFO) BYTE ; 

DECLARE FUNC BYTE, INFO ADDRESS; 
GO TO ENTRY; 



END MON2 7 
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c) r 

MONl : PROCEDURE (FUNC , INFO) ; 

DECLARE FUNC BYTE, INFO ADDRESS; 
GO TO ENTRY; 
END MONl 

if no returned value is expected. 
2.1 Direct and Buffered I/O. 

The BIOS entry points are given in Table I. In the case of 
simple character I/O to the console, the BIOS reads the console 
device, and removes the parity bit. The character is echoed back 
to the console, and tab characters (control-I) are expanded to 
tab positions starting at column one and separated by eight char- 
acter positions. The I/O status byte takes the form shown in 
Table I, and can be programmatically interrogated or changed. 
The buffered read operation takes advantage of the CP/M line edit- 
ing facilities. That is, the program sends the address of a read 
buffer whose first byte is the length of the buffer. The second 
byte is initially empty, but is filled-in by CP/M to the number 
of characters read from the console after the operation (not 
including the terminating carriage-return) . The remaining posi- 
tions are used to hold the characters read from the console. The 
BIOS line editing functions which are performed during this oper- 
ation are given below: 

break - line delete and transmit 

rubout - delete last character typed, and echo 

control-C - system reboot 

control-U - delete entire line 

control-E - return carriage, but do not transmit 
buffer (physical carriage return) 

<cr> - transmit buffer 



The read routine also detects control character sequences other 
than those shown above, and echos them with a preceding "t" 
symbol. The print entry point allows an entire string of symbols 
to be printed before returning from the BIOS. The string is 
terminated by a "$" symbol. 

2.2 A Simple Example 

As an example, consider the following PL/M procedures and 
procedure calls which print a heading, and successively read 
the console buffer. Each console buffer is then echoed back in 
reverse order: 
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PRINTCHAR: PROCEDURE (B) ; 

/* SEND THE ASCII CHARACTER B TO THE CONSOLE */ 
DECLARE B BYTE ; 
CALL MONK 2, B) : 
END PRINTCPIAR; 



CRLF: PROCEDURE 7 

/* SEND CARRIAGE-RETURN-LINE-FEED CHARACTERS */ 
CALL PRINTCHAR (ODH); CALL PRINTCHAR (OAH); 
END CRLF; 



PRINT: PROCEDURE (A) ; 

/* PRINT THE BUFFER STARTING AT ADDRESS A */ 
DECLARE A ADDRESS; 
CALL M0N1(9,A) ; 
END PRINT; 

DECLARE RDBUFF (130) BYTE; 



READ: PROCEDURE; 

/* READ CONSOLE CHARACTERS INTO 'RDBUFF' */ 
RDBUFF=128; /* FIRST BYTE SET TO BUFFER LENGTH */ 
CALL MONl (10 , . RDBUFF) ; 
END READ; 

DECLARE I BYTE; 

CALL CRLF; CALL PRINT (.'TYPE INPUT LINES $'); 

DO WHILE 1; /* INFINITE LOOP-UNTIL CONTROL-C */ 
CALL CRLF; CALL PRINTCHAR ('*'); /* PROMPT WITH '*' */ 
CALL READ; I = RDBUFF(l); 

DO WHILE (I := I -1) <y 255; 

CALL PRINTCHAR (RDBUFF ( 1+2 )) ; 

END; 

END; 



The execution of this program might proceed as follows: 



TYPE INPUT LINES 

*HELLO, 

OLLEH 

*WALL WALLA WASH, * 
HSAW ALLAW ALLAW 
*MOM WOW^ 
WOW MOM 

*tc (system reboot) 
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TABLE I 
BASIC I/O OPERATIONS 



function/ 

NUMBER 


ENTRY 
PARAMETERS 


RETURNED 
VALUE 


TYPICAL 
CALL 


Read Console 
1 


, 1 ii .1. 

None 


ASCII Character 


I = MON2(1,0) 


Write Console 
2 


ASCII Character 


None 


CALL MONl (2, 'A' ) 


Read Reader 
3 


None 


ASCII Character 


I = MON2(3,0) 


Write Punch 
4 


ASCII Character 


None 


CALL MONl (4, 'B") 


Write Lxst 
5 


ASCII Character 


None 


. CALL MONl { 5 , ' C ' ) 


Get I/O Status 
7 


None 


I/O Status Byte 


I0STAT=M0N2 (7,0) 


Set I/O Status 
8 


I/O Status Byte 


None 


CALL MONl (8, lOSTAT) 


Print Buffer 
9 


Address of 
string termi- 
na ted by ' $ ' 


None 


CALL MONl (9, . ' PRINT 
THIS $') 
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TABLE I (continued) 



FUNCTION/ 
NUMBER 


ENTRY 
PARAMETERS 


RETURNED 
VALUE 


TYPICAL 
CALL 


Read Buffer 
10 


Address of 
Read Buffer* 

(See Note^) 


Read buffer is 
filled to maxi- 
mum length with 
console charac- 
ters 


CALL MONKIO, 
.RDBUFF) 7 


Interroga te 
Console Ready 

11 


None 


Byte value with 
least signifi- 
cant bit = 1 
(true) if con- 
sole character 
is ready 


I = MON2(11,0) 



Note. 



Read buffer is a sequence of memory locations of the form: 



Note, 



m k c 



t '^current buffer length 
'—Maximum buffer length 

The I/O status byte is defined as three fields A,B,C, and D 

2b 2b 2b 2b 



B 



D 



MSB 



LSB 



requiring two bits each, listed from most significant to least 
significant bit, which define the current device assignment as 
follows : 



D 

Console 



0 TTY '^ 

1 CRT \ 

2 BATCHj 



'0 TTY 
C = ; 1 FAST READER 
Reader \ 2 



"0 TTY TTY 
B = i 1 FAST PUNCHV A = J 1 CRT 
Punch \ 2 - J List \^ 2 - 
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3. DISK I/O FACILITIES 

The BDOS section of CP/M provides access to files stored on 
diskettes. The discussion which follows gives the overall file 
organization, along with file access mechanisms. 

3.1 File Organization 

CP/M implements a named file structure on each diskette, pro- 
viding a logical organization which allows any particular file to 
contain any number of records, from completely empty, to the full 
capacity of a diskette. Each diskette is logically distinct, 
with a complete operating system, disk directory, and file data 
area. The disk file names are in two parts: the *^filename> 
which can be from one to eight alphanumeric characters, and the 
"^filetype^ which consists of zero through three alphanumeric 
characters. The <filetype> names the generic category of a par- 
ticular file, while the <filename> distinguishes a particular 
file within the category. The <filetype> s listed below give 
some generic categories which have been established, although 
they are generally arbitrary: 

ASM assembler source file 

PRN assembler listing file 

HEX assembler or PL/M machine code 
in "hex" fomat 

BAS BASIC Source file 

INT BASIC Intermediate file 

COM Memory image file (i.e., "Command" 

file for transients, produced by LOAD) 

BAK Backup file produced by editor 
(see ED manual) 

$$$ Temporary files created and normally 
erased by editor and utilities 

Thus , the name 

X.ASM 

is interpreted as an assembly language source file by the CCP 
with *^filename> X. 

The files in CP/M are organized as a logically contiguous se- 
quence of 128 byte records (although the records may not be phys- 
ically contiguous on the diskette) , which are normally read or 
written in sequential order. Random access is allowed under CP/M 
however, as described in Section 3.4. No particular format with- 
in records is assumed by CP/M, although some transients expect 
particular formats: 
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and 



(1) Source files are considered a sequence of 
ASCII characters, where each "line" of the 
source file is followed by carriage-return- 
line-rfeed characters. Thus, one 128 byte 
CP/M record could contain several logical 
lines of source text. Machine code "hex" 
tapes are also assumed to be in this for- 
mat, although the loader does not require 
the carriage-return-line-feed characters. 
End of text is given by the character con- 
trol-z, dr real end-of-file returned by 
CP/M. 



(2) COM files are assumed to be absolute machine 
code in memory image form, starting at tbase 
in memory. In this case, control-z is not 
considered an end of file, but instead is 
determined by the actual space allocated 
to the file being accessed. 



3.2 File Control Block Format 

Each file being accessed through CP/M has a corresponding 
file control block (FCB) which provides name and allocation 
information for all file operations. The FCB is a 33-byte area 
in the transient program's memory space which is set up for each 
file. The FCB format is given in Figure 2. When accessing CP/M 
files, it is the programmer's responsibility to fill the. lower 
16 bytes of the FCB, along with the CR field. Normally, the FN 
and FT fields are set to the ASCII <filename> and <filetype>, 
while all other fields are set to zero. Each FCB describes up 
to 16K bytes of a particular file (0 to 128 records of 128 bytes 
each) , and, using automatic mechanisms of CP/M, up to 15 addi- 
tional extensions of the file can be addressed. Thus, each FCB 
can potentially describe files up to 256K bytes (which is slightly 
larger than the diskette capacity) . 

FCB's are stored in a directory area of the diskette, and are 
brought into central memory before file operations (see the OPEN 
and MAKE commands) then updated in memory as file operations pro- 
ceed, and finally recorded on the diskette at the termination of 
the file operation (see the CLOSE command) . This organization 
makes CP/M file organization highly reliable, since diskette file 
integrity can only be disrupted in the unlikely case of hardware 
failure during update of a single directory entry. 

It should be noted that the CCP constructs ah FCB for all 
transients by scanning the remainder of the line following the 
transient name for a <filename> or <f ilename>- <f iletype> com- 
bination. Any field not specified is assumed to be all blanks. 
A properly formed FCB is set up at location tfcb (see Section 6), 
with an assumed I/O buffer at tbuff . The transient can use tfcl? 
as an address in subsequent input or output operations on this 
file. 
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In addition to the default fob which is set-up at address tfcb, the 
CCP also constructs a second default fcb at address tfcb+16 (i.e., the 
disk map field of the fcb at tbase) . Thus, if the user types 

PROGNAME X . ZOT Y . ZAP 

the file PP0GNAME.COM is J.oaded to the TPA, and the default fcb at tfcb 
is initialized to the filename X with filetype ZOT. Since the user typed 
a second file name, the 16 byte area beginning at tfcb + ISj^g also 
initialized with the filename Y and filetype ZAP. It is the responsibility 
of the program to move this second filename and filetype to another area 
(usually a separate file control block) before opening the file which 
begins at tbase, since the open operation will fill the disk map portion, 
thus overwriting the second name and type. 

If no file names were specified in the original command, then the 
fields beginning at tfcb and tfcb + 16 both contain blanks (20H) . If 
one file name was specified, then the field at tfcb + 16 contains blanks. 
If the filetype is omitted, then the field is assumed to contain blanks. 
In all cases, the CCP translates lower case alphabetics to upper case 
to be consistent with the CP/M file namiing conventions. 

As an added programming convenience, the default buffer at tbuff 
is initialized to hold the entire command line past the program name. 
Address tbuff contains the number of characters, and tbuff +1, tbuff +2, 
. ^. , contain the remaining characters up to, but not including, the 
carriage return. Given that the above command has been typed at 
the console, the area beginning at tbuff is set up as follows: 

tbuff: 

+0 +1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 
12]6X.ZOTJdY.ZAP??? 



where 12 is the number of valid characters (in binary) , and }6 represents 
an ASCII blank. Characters are given in ASCII upper case, with un- 
initialized memory following the last valid character. 

Again, it is the responsibility of the program to extract the infor- 
mation from this buffer before any file operations are performed since 
the FDOS uses the tbuff area to perform directory functions. 

In a standard CP/M system, the following values are assumed: 

boot: OOOOH bootstrap load twarm start) 

entry: 0005H entry point to FDOS 

tfcb: 005CH first default file control block 

tfcb+16 006CH second file name 

tbuff 0080H default buffer address 

tbase: OlOOH base of transient area 



Figure 2. File Control Block Format 
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 27 28 29 30 31 32 



ET 



FN 



FT EX 



RC 



DM 



NR 



FIELD 



ET 



FN 



FCB POSITIONS 



1-8 



PURPOSE 

Entry type (currently not used, 
but assumed zero) 

File name, padded with ASCII 
blanks 



FT 



9-11 



File type, padded with ASCII 
blanks 



EX 



12 



File extent, normally set to 
zero 



RC* 



DM 



NR 



13-14 
15 

16-31 

32 



Not used, but assumed zero 

Record count is current extent 
Size (0 to 12 8 records) 

Disk allocation map, filled-in 
and used by CP/M 

Next record number to read or 
write 
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3.3 Disk Access Primitives 

Given that a program has properly initialized the FCB's for 
each of its files, there are several operations which can be per- 
formed, as shown in Table II. In each case, the operation is 
applied to the currently selected disk (see the disk select oper- 
ation in Table II) , using the file information in a specific FCB. 
The following PL/M program segment, for example, copies the con- 
tents of the file X.Y to . the (new) file NEW.FIL: 



DECLARE RET BYTE; 
OPEN: 



CLOSE 



MAKE 



DELETli: 



READBF 



WRITEBF 



INIT 



PROCEDURE (A) 
DECLARE A ADDRESS; 
RET=M0N2 (15,A) ; 
END OPEN; 

PROCEDURE (A) ; 
DECLARE A ADDRESS; 
RET=M0N2 (16, A) ; 
END; 

PROCEDURE (A) ; 
DECLARE A ADDRESS; 
RET=iyiON2 (22, A) ; 
END MAKE; 

PROCEDURE (A) ; 

DECLARE A ADDRESS; 

/* IGNORE RETURNED VALUE */ 

CALL MONl (19,A) ; 

END DELETE; 

PROCEDURE (A) ; 
DECLARE A ADDRESS; 
RET=M0N2 (20, A) ; 
END READBF; 

PROCEDURE (A) ; 
DECLARE A ADDRESS; 
RET=M0N2 (21, A) ; 
END WRITEBF; 

PROCEDURE ; 

CALL MONl (13,0) ; 

END INIT; 



/* SET UP FILE CONTROL BLOCKS */ 
DECLARE FCBl (33) BYTE 

INITIAL (0, 'X ','Y ',0,0,0,0), 

FCB2 (33) BYTE 

INITIAL (0,'NEW ' , ' FIL ' , 0, 0 , 0, 0 ) ; 
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CALL INIT; 

/* ERASE 'NEW.FIL' IF IT EXISTS */ 
CALL DELETE ( . FCB2 ) ; 

/* CREATE' 'NEW.FIL' AND CHECK SUCCESS */ 
CALL MAKE ( .FCB2) ; 

IF RET = 255 THEN CALL PRINT (.'NO DIRECTORY SPACE $'); 
ELSE 

DO; /* FILE SUCCESSFULLY CREATED, NOW OPEN 'X.Y' */ 
CALL OPEN ( .FCBl) 7 

IF RET = 255 THEN CALL PRINT (.'FILE NOT PRESENT $'); 
ELSE 

DO; /* FILE X.Y FOUND AND OPENED, SET 
NEXT RECORD TO ZERO FOR BOTH FILES */ 
FCBl (32) , FCB2 (32) = 0; 

/* READ FILE X.Y UNTIL EOF OR ERROR */ 
CALL READBF (.FCBl); /*READ TO 80H*/ 
DO WHILE RET =0; 

CALL WRITEBF (.FCB2) /*WRITE FROM 80H*/ 
IF RET = 0 THEN /*GET ANOTHER RECORD*/ 

CALL READBF (.FCBl); ELSE 

CALL PRINT (. 'DISK WRITE ERROR $') ; 
END; 

IF RET < >1 THEN CALL PRINT (.' TRANSFER ERROR $'); 
ELSE 

DO; CALL CLOSE (.FCB2); 

IF RET = 255 THEN CALL PRINT (.'CLOSE ERROR? ') ; 
END; 
END; 
END; 

EOF 

This program consists of a number of utility procedures for 
opening, closing, creating, and deleting files, as well as two 
procedures for reading and writing data. These utility procedures 
are followed by two FCB's for the input and output files. In 
both cases, the first 16 bytes are initialized to the <filename> 
and "^filetype^ of the input and output files. The main program 
first initializes the disk system, then deletes any existing 
copy of "NEW.FIL" before starting. The next step is to create 
a new directory entry (and empty file) for "NEW.FIL". If file 
creation is successful, the input file "X.Y" is opened. If this 
second operation is also successful, then the disk to disk copy 
can proceed. The NR fields are set to zero so that the first 
record of each file is accessed on subsequent disk I/O operations. 
The first call to READBF fills the (implied) DMA buffer at 80H 
with the first record from X.Y. The loop which follows copies 
the record at BOH to "NEW.FIL" and then reports any errors, or 
reads another 128 bytes from X.Y. This transfer operation con- 
tinues until either all data has been transferred, or an error 
condition arises. If an error occurs, it is reported; other- 
wise the new file is closed and the program halts. 



TABLE II 
DISK ACCESS PRIMITIVES 



r U Di\^ X J. U IN/ IN U 1X1X3 HiK 




KbiUKNriU VALiUb 


ixFlL.H.ij UiiLiij 


Lift Head 
12 


None 


None 

Head is lifted from 
current drive 


CALL M0N2 (12,0) 


J. IIX^X dX X /• c OLywO 

and select disk 
"A" 

Set DMA address 
to 80H 

13 


LNOn6 


None 

Side effect is that 
disk A is "logged- 
in" while all others 
are considered "off- 
line" 




Log -in and 
select disk 
X 

14 


An integer value cor- 
responding to the 
disk to log -in: 
A=0, B=l, C=2, etc. 


None 

Disk X is considered 
"on-line" and selec- 
ted for subsequent 
file operations 


CALL MONl (14 ,1) 
(log-in disk "B") 


upen nxe 
15 


Aaaress or une tl-d 
for the file to be 
accessed 


rjyue aaaress or tne 
FCB in the directory, 
if found, or 255 if 
file not present. 
The DM bytes are set 
by the BDOS. 


1 — ilU INZ V-Lj, .rv^Dj 


Close file 
16 


Address of an FCB 
which has been pre- 
viously created or 
opened 


Byte address of the 
directory entry cor- 
responding to the 
FCB, or 255 if not 
present 


I = M0N2 (16, .FCB) 


1 A 



TABLE II (continued) 



FUNCTION/NUMBER 



ENTRY PARAMETERS 



RETURNED VALUE 



TYPICAL CALL 



Search for file 
17 



Address of FCB con- 
taining <filename> 
and <filetype> to 
match. ASCII "?" 
in FCB matches any 
character . 



Byte address of first 
FCB in directory that 
matches input FCB, if 
any; otherv/ise 2 55 
indicates no match. 



I = M0:;2 (17, .FCB) 



Search for next 
occurrence 

18 



Same as above, but 
called after func- 
tion 17 (no other 
intermediate BDOS 
calls allowed) 



Byte address of next 



I = M0N2 (18, .FCB) 



Delete File 
19 



Address of FCB con- 
taining <filename> 
and <filetype> of 
file to delete from 
diskette 



None 



I = M0N2 (19, .FC. ) 



Read Next Record 
20 



Address of FCB of a 
successfully OPENed 
file, with NR set 
to the next record 
to read (see note^) 



0 = successful read 

1 = read past end of 

file 

2 = reading unwritten 

data in random 
access 



I = M0N2 (20, .FCB) 



Note 



1* 



The I/O operations transfer data to/from addre'fis 80H for the next 12 8 byt^js unless 
the DMA address has been altered (see function 26) . Further, the NR field of the 
FCB is automatically incremented after the operation. If the NR field exceeds 128, 
the next extent is opened automatically, and the NR field is reset to zero. 



15 



TABLE II (continued) 



FUNCTION/NUMBER ENTRY PARAMETERS RETURNED VALUE TYPICAL CALL 



Write Next Record 


Same as above, except 


0 = successful write 


I 


= MON 2(21, 


. FCB) 


21 


NR is set to the next 


1 = error in extend- 








record to write 


ing file 
2 = end of disk data 
255 = no more dir- 
ectory space 
(see note2) 








Make File 


Address of FCB with 


Byte address of dir- 


I 


= MON2(22, 


.FCB) 


22 


<filename> and <file- 


ectory entry alloca- 








type> set. Direc- 
tory entry is cre- 
ated, the file is 
initialized to empty. 


ted to the FCB, or 
255 if no directory 
space is available 








Kename r l.o 


Aaaress or tl-d wiun 
old FN and FT in 


/\uicir6oo oi uiic aj-ir 
ectory entry which 


T 
X 
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first 16 bytes, and 
new FN and FT in 
second 16 bytes 


matches the first 
16 bytes. The 
<f ilename>and <file- 
type> is altered 
255 if no match. 









Note2: There are normally 64 directory entries available on each diskette (can be 
expanded to 255 entries) , where one entry is required for the primary file, 
and one for each additional extent. 
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TABLE II (continued) 



FUNCTION/NUMBER ENTRY PARAMETERS RETURNED VALUE TYPICAL CALL 



Interrogate log- 
in vector 

24 



None 



Byte value with "1" 
in bit positions of 
"on line" disks, 
with least signi- 
ficant bit corres- 
ponding to disk "A" 



I = M0N2 (2 4,0) 



Set DMA address 
26 



Address" of 
DMA buffer 



12 8 byte 



None 

Subsequent disk I/O 
takes place at spe- 
cified address in 
memory 



CALL MONl (26,2000H) 



Interrogate 
Allocation 

27 



None 



Address of the allo- 
cation vector for 
the current disk 
(used by STATUS com- 
mand) 



M0N3 : PROCEDURE (...) 
ADDRESS; 

A = MON3(27,0) ; 



Interrogate Drive 
number 

25 



None 



Disk number of currently 
logged disk (i.e., the 
drive which will be used 
for the next disk operation 



I = MON2(25,0) ; 
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3.4 Random Access 

Recall that a single FCB describes up to a 16K segment of a 
(possibly) larger file. Random access within the first 16K seg- 
ment is accomplished by setting the NR field to the record number 
of the record to be accessed before the disk I/O takes place. 
Note, however, that if the 128th record is written, then the 
BDOS automatically increments the extent field (EX), and opens 
the next extent, if possible. In this case, the program must 
explicitly decrement the EX field and re-open the previous extent. 
If random access outside the first 16K segment is necessary, 
then the extent' number e be explicitly computed, given an absol- 
ute record number r as 

^ = L ikl 

or equivalently , 

e = SHR(r,7) 

this extent number is then placed in the EX field before the seg- 
ment is opened. The NR value n is then computed as 

n = r mod 128 

or 

n = r AND 7FH. 

When the programmer expects considerable cross-segment accesses, 
it^may save time to create an FCB for each of the 16K segments, 
open all segments for access, and compute the relevant FCB from 
the absolute record number r. 



4. SYSTEM GENERATION 

As mentioned previously, every diskette used under CP/M is assimed to 
contain the entire system (excluding transient commands) on the first two 
tracks. The operating system need not be present, however, if the diskette 
is only used as secondary disk storage on drives B, C, — , since the CP/M 
systan is loaded only from drive A. 

The CP/M file system is organized so that an IBM-compatible diskette 
from the factory (or from a vendor which claims IBM compatibility) looks 
like a diskette with an empty directory. Thus, the user must first copy 
a version of the CP/M system from an existing diskette to the first two 
tracks of the new diskette, followed by a sequence of copy operations, 
using PIP, which transfer the transient command files from the original 
diskette to the new diskette. 
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NOTE: before you begin the CP/M copy operation, read your Licensing 
Agreement. It gives your exact legal obligations when making reproductions 
of CP/M in whole or in part, and specifically requires that you place the 
copyright notice 

Copyright (c) , 1976 
Digital Research 

on each diskette which results from the copy operation, 
4.1. Initializing CP/M from an Existing Diskette 

The first two tracks are placed on a new diskette by running the tran- 
sient command SYSGEN, as described in the document "An Introduction to CP/M 
Featiires and Facilities." The SYSGEN operation brings the CP/M system from 
an initialized diskette into memory, and then takes the memory image and 
places it on the new diskette. 

Upon completion of the SYSGEN operation, place the original diskette 
on drive A, and the initialized diskette on drive B. Reboot the system; 
the response should be 

A> 

indicating that drive A is active. Log into drive B by typing 

B: 

and CP/M should respond with 

B> 

indicating that drive B is active. If the diskette in drive B is factory 
fresh, it will contain an empty directory. Non-standard diskettes may, 
however, appear as full directories to CP/M, which can be emptied by typing 

ERA *.*^ 

when the diskette to be initialized is active. Do not give the ERA command 
if you wish to preserve files on the new diskette since all files will be 
erased with this command. 

After examining disk B, reboot the CP/M system and return to drive A for 
further operations. 

The transient commands are then copied from drive A to drive B using the 
PIP program. The sequence of commands shown below, for example, copy the 
principal programs from a standard CP/M diskette to the new diskette: 

A>PIP, 

*B : STAT . COM=STAT . COM^ 
*B :PIP . COM=PIP . COM ^ 
*B : LOAD . COM=LOAD . COM^ 
*B:ED.COM=ED.COM> 
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*B : ASM. COM=ASM. COM^ 

*B : SYSGEN . COM=SYSGEN . COM 

*B : DDT . COM=DDT . COMp 

A> 



The user should than log in disk B, and type the command 



DIR *.*^ 

to ensure that the files were transferred to drive B from drive A. The 
various programs can then be tested on drive B to check that they were 
transferred properly. 

Note that the copy operation can be simplified somewhat by creating 
a "submit" file which contains the copy commands. The file could be 
named GEN. SUB, for example, and might contain 



SYSGEN^ 

PIP B : STAT . COM=STAT . COM^ 

PIP B:PIP.COM=PIP.COM^ 

PIP B: LOAD. COM=LOAD. COM, 

PIP B : ED. COMBED. COM^ 

PIP B:ASM.COM=ASM.CO^^ 

PIP B: SYSGEN. COM=SYSGEN.COM^ 

PIP B:DDT.COM=DDT.COM, 

The generation of a new diskette from the standard diskette is then done 
by typing simply 

SUBMIT GEN, 



5. CP/M ENTRY POINT SUMMARY 

The functions shown below summarize the functions of the 
FDOS. The function number is passed in Register C (first para- 
meter in PL/M) , and the information is passed in Registers D,E 
(second PL/M parameter) . Single byte results are returned in 
Register A. If a double byte result is returned, then the high- 
order byte comes back in Register B (normal PL/M return) . The 
transient program enters the FDOS through location "entry" (see 
Section 7.) as shown in Section 2. for PL/M, or 



CALL entry 



in assembly language. All registers are altered in the FDOS. 
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Function Number Information Result 

0 System Reset 

1 Read Console ASCII character 

2 Write Console ASCII character 

3 Read Reader ASCII character 

4 Write Punch ASCII character 

5 Write List ASCII character 

6 (not used) 

7 Interrogate I/O Status I/O Status Byte 

8 Alter I/O Status I/O Status Byte 

9 Print Console Buffer Buffer Address 

10 Read Console Buffer Buffer Address 

11 Check Console Status True if character 

Ready 

12 Lift Disk Head 

13 Reset Disk System 

14 Select Disk Disk number 

15 Open File FCB Address Completion Code 

16 Close File 

17 Search First 

18 Search Next 

19 Delete File " " " 

20 Read Record 

21 Write Record " " " 

22 Create File 

23 Rename File " " " " 

24 Interrogate Login Login Vector 

25 Interrogate Disk Selected Disk 

Number 

26 Set DMA Address DMA Address 

27 Interrogate Allocation Address of Allo- 

cation Vector 
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6. ADDRESS ASSIGNMENTS 

The standard distribution version of CP/M is organized for an Intel 
MDS microcomputer developmental system with 16K of main memory, and two 
diskette drives. Larger systems are available in 16K increments, providing 
management of 32K, 48K, and 64K systems (the largest MDS system is 62K 
since the POM monitor provided with the MDS resides in the top 2K of the 
memory space) . For each additional 16K increment, add 4000H to the values 
of cbase cuid fbase. 

The address assignments ajce 



boot = OOOOH 
tfcb = 005CH 
tbuff= 0080H 
tbase= OlOOH 
cbase= 2 90 OH 
fbase= 3200H 
entry= 000 5H 



warm start operation 

default file control block location 

default buffer location 

base of transient program area 

base of console command processor 

base of disk operating system 

entry point to disk system fron 

user programs 
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7. SAMPLE PROGRAMS 

This section contains two sample programs which interface with the CP/M 
operating system. The first program is written in assembly language, and 
is the soiirce program for the DUMP utility. The second program is the CP/M 
LOAD utility, written in PL/M. 

The assembly language program begins with a number of "equates" for sys- 
tem entry points and program constants. The equate 

BDOS EQU 0005H 

for example, gives the CP/M entry point for peripheral I/O functions. The 
defualt file control block address is also defined (FCB) , along with the 
default buffer address (BUFF) . Note that the program is set up to run at 
location lOOH, which is the base of the transient program area. The stack 
is first set-up by saving the entry stack pointer into OLDSP, and resetting 
SP to the local stack. The stack pointer upon entry belongs to the console 
command processor, and need not be saved unless control is to return to the 
CCP upon exit. That is, if the program terminates with a reboot (brancji to 
location OOOOH) then the entry stack pointer need not be saved. 

The program then jumps to MAIN, past a number of subroutines which *are 
listed below: 

BREAK - when called, checks to see if there is a console 

character ready. BREAK is used to stop the listing 
at the console 

PCHAR - print the character which is in register A at the 
console . 

CRLF - send carriage return and line feed to the console 

PNIB - print the hexadecimal value in register A in ASCII 
at the console 

PHEX - print the byte value (two ASCII characters) in 
register A at the console 

ERR - print error flag #n at the console, where n is 

1 if file cannot be opened 

2 if disk read error occurred 

GNB - get next byte of data from the input file. If the 
IBP (input buffer pointer) exceeds the size of the 
input buffer, then another disk record of 128 bytes 
is read. Otherwise, the next character in the buffer 
is returned. IBP is updated to point to the next 
character. 
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The MAIN program then appears, which begins by calling SETUP. The SETUP 
subroutine, discussed below, opens the input file and checks for errors. 
If the file is opened properly, the GLOOP (get loop) label gets control. 

On each successive pass through the GLOOP label, the next data byte 
is fetched using GNB and save in register B. The line addresses are listed 
every sixteen bytes, so there must be a check to see if the least signi- 
ficant 4 bits is zero on each output. If so, the line address is taken 
from registers h and 1, and typed at the left of the line. In all cases, 
the byte which was previously saved in register B is brought back to 
register A, following label NONUM, and printed in the output line. The 
cycle through GLOOP continues until an end of file condition is detected 
in DISKR, as described below. Thus, the output lines appear as 

0000 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 
0010 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 



until the end of file. 

The label FINIS gets control upon end of file. CRLF is called first 
to return the carriage from the last line output. The CCP stack pointer 
is then reclainied from OLDSP, followed by a RET to return to the console 
command processor. Note that a JMP OOOOH could be used following the 
FINIS label, which would cause the CP/M system to be brought in again from 
the diskette (this operation is necessary only if the CCP has been over- 
layed by data areas) . 

The file control block format is then listed (FCBDN . . . FCBLN) which 
overlays the fob at location 05CH which is setup by the CCP when the 
DUMP program is initiated. That is, if the user types 

DUMP X.Y 

then the CCP sets up a properly fo2niied fob at location 05CH for the DUMP 
(or any other) program when it goes into execution. Thus, the SETUP sub- 
routine simply addresses this default fob, and calls the disk system to 
open it. The DISKR (disk read) routine is called whenever GNB needs another 
buffer full of data. The default buffer at location 80H is used, along 
with a pointer (IBP) which counts bytes as they are processed. Normally, 
an end of file condition is taken as either an ASCII lAH (control-z) , or 
an end of file detection by the DOS. The file dump program, however, stops 
only on a DOS end of file. 



FILE DUMP PROGRAM, READS AN INPUT FILE AND PRINTS IN HEX 



COPYRIGHT (C) , DIGITAL RESEARCH, 1975, 1976 



V X XIV 






■ ^N^rvvj 


1 CI CIH 
Xtivvi 




tJlJVJ 








a M <i c u 


• UUO CLNXKl C\J Xv* X 


000F 




OPENF 


EQU 


15 


•FILE OPEN 


0014 




READF 


EOU 


20 ; 


•READ FUNCTION 






rpv DPP 




2 ; 


•TYPE FUNCTION 


0001 


= 


CONS 


EQU 


1 


•READ CONSOLE 


0006 




BRKF 


EOU 


11 


•BREAK KEY FUNCTION (TRUE IF 






7 

PCR 


Fnri 


5CH 7 FILE CONTROL BLOCK ADDRESS 


vVOv 




Rn p P 
ou r r 

* 


pnn 


80H ;INPUT DISK BUFFER ADDRESS 






• 


qpf rip 


STACK 




Oil (Pi 


91 (^(^OiOi 

£,Xv tlvv 




X 


H,0 




Oil C\'i 


39 




DAD 


SP 




0104 


220F01 




SHLD 


OLDSP 




0107 


315101 




LXI 


SP,STKTOP 


Oil 01 A 


r> op A Oil 




JMP 


MAIN 








7 


VARIABLES 




CI 1 n 

Y)±\OU 




T D D • 

XDt I 


DS 


2 7 INPUT BUFFER POINTER 






• 

/ 

• 


STACK AREA 




010F 




OLDSP: 


DS 


2 




0111 




STACK: 


DS 


64 




Oil m 






EOU 


$ 










SUBROUTINES 










?CflECK 


BREAK KEY 


(ACTUALLY ANY KEY WILL DO) 


0151 


E5D5C5* 




PUSH HI 


PUSH Dl PUSH B; ENVIRONMENT SAVED 


0154 


0E0B 




MVI 


CBRKF 






CViOi KOi ot 




CALL 


BDOS 




Oil f^Q 


n m P'l 




POP BI 


POP Di POP Hr ENVIRONMENT RESTORED 


Oil 






RET 










* 

DP HAD • 


7 PRINT 


A CHARACTER 


ai t^n 






PUSH H! 


PUSH Dl PUSH B? SAVED 


0160 


0E02 




MVI 


CTYPEF 




0162 


5F 




MOV 


E,A 




oil fi'k 

19 J. O J 


rr.oif>OiOi 




CALL 


BDOS 




Oil (id 
10 J. 0 0 


n m PI 

\^ XUX CjX 




POP Bl 


POP Dl POP H? RESTORED 


Oil 


C Q 
v.* y 




RET 










7 

TRT F • 

^r\.xir • 








016A 


3E0D 




MVI 


A,0DH 




Oil fir 


J Uv X 




CALL 


PCHAR 




016F 


3E0A 




MVI 


A,0AH 




Oil 11 
V X / X 


y^UD Uv X 




CALL 


PCHAR 




Oil 1 A 
V X / H 




7 


RET 










PNIB: 


7 PRINT 


NIBBLE IN 


REG A 


0175 


E60F 




ANI 


0FH 7LOW 4 BITS 


0177 


FE0A 




CPI 


10 




0179 


D28101 




JNC 


P10 





017C C630 
ill7E C38301 



LESS THAN OR EQUAL TO 9 
ADI '0' 
JMP PRN 



0181 C637 P10: 
0183 CD5D01 PRM: 
0186 C9 



GREATER OR EQUAL TO 10 



ADI 

CALL 

RET 



A - 10 
PCHAR 



PHEX: ; PRINT HEX CHAR IN REG A 



0187 
0188 
0189 
018A 
0183 
018C 
018F 
0190 
0193 



F'5 
0F 
0F 
0F 
0F 

CD7501 
Fl 

CD7501 
C9 



PUSH 

RRC 

RRC 

RRC 

RRC 

CALL 

POP 

CALL 

RET 



PSW 



PNIB 

PS\M 

PNIB 



PRINT NIBBLE 



ERR 



; PRINT ERROR MESSAGE 



0194 
0197 
0199 
019C 
019D 
019F 
01A2 
01A5 



CD6A01 
3E23 
CD5D01 
78 

C630 
CD5D01 
CD6A01 
C3F701 



CALL 

MVI 

CALL 

MOV 

ADI 

CALL 

CALL 

JMP 



CRLF 
A, '#' 
PCHAR 
A,B 
'0' 

PCHAR 

CRLF 

FINIS 



01A8 3A0D0J. 
01AB FE80 
01AD C2B401 



0180 
01B3 



CD1602 
AF 



GNB: ;GET NEXT BYTE 
LDA IBP 
CPI 80H 
JNZ G0 
READ ANOTHER BUFFER 



CALL 
XRA 



DISKR 
A 



01B4 5F 

01B5 1600 

0167 3C 

01B8 320D01 



01BB E5 

01BC 218000 

01BF 19 

01C0 7E 



01C1 El 
iaiC2 23 
01C3 C9 



01C4 CDFF01 



G0: ;READ THE BYTE AT BUFF+REG A 

MOV E,A 

MVI D,0 

INR A 

STA IBP 
; POINTER IS INCREMENTED 

; SAVE THE CURRENT FILE ADDRESS 

PUSH H 

LXI H^BUFF 

DAD D 

MOV A,M 

BYTE IS IN THE ACCUMULATOR 

RESTORE FILE ADDRESS AND INCREMENT 
POP H 
INX H 
RET 

MAIN: ; READ AND PRINT SUCCESSIVE BUFFERS 
CALL SETUP ;SET UP INPUT FILE 



01C7 


3E80 




MVI 


A,80H 


01C9 


320D01 




3TA 


IBP ;SET BUFFER POINTER TO 80H 


01CC 


21FFFF 


• 


LXI 


H,0FFFFH ;S£T TO -1 TO START 






\JJLt<J\J C • 






01CF 


CDA801 




CALL 


GNB 


01D2 


47 




MOV 


B,A 






• 


PRINT 


HEX VALUES 






• 


CHECK 


FOR LINE FOLD 


01D3 


ID 




MOV 


A,L 


M 1 Hid 


P (^Oiit- 




2iM T 




01D6 


C2EB01 




JMZ 


NONUM 






• 


PRINT 


LINE NUMBER 


01D9 


CD6A01 


• 


CALL 


CRLF 






t 

7 






01DC 


CD5101 




CALL 


BREAK 


01DF 


0F 




RRC 




01E0 


DAP701 


• 


JC 


FINIS ;DON'T PRINT ANY MORE 


01E3 


7C 




MOV 


A,H 


01E4 


CD8701 




CALL 


PHEX 


01E7 


7D 




MOV 


A,L 


01E8 


CD8701 




CALL 


PHEX 






NONUM: 






VJ ± CiO 


P 9 CI 






n ' ' 


01ED 


CD5D01 




CALL 


PCHAR 




7 8 








01F1 


CD8701 




CALL 


PHEX 


01F4 


C3CF01 


• 


JMP 


GLOOP 






EPSA: 


;END 


PSA 








• 

/ 


END OF INPUT 






FINIS: 






01F7 


CD6A01 




CALL 


CRLF 


01FA 


2A0F01 




LHLD 


OLDSP 


01FD 


F9 




SPHL 




01FE 


C9 


; 


RET 








• 

; 


FILE 


CONTROL BLOCK DEFINITIONS 


005C 


= 


FCBDN 


EQU 


FCB+0 ;DISK NAME 


005D 




FCBFN 


EQU 


FCB+1 ;FILE NAME 


0065 




FCBFT 


EQU 


FCB+9 ;DISK FILE TYPE (3 CHARACTERS) 


0068 




FCBRL 


EQU 


FCB+12 ;FILE'S CURRENT REEL NUMBER 


006B 




FCBRC 


EQU 


FCB+15 ;FILE''S RECORD COUNT (0 TO 128) 


007C 




FCBCR 


EQU 


FCB+32 ;CURRENT (NEXT) RECORD NUMBER (0 


007D 




FCBLN 

• 


EQU 


FCB+3 3 ;FCB LENGTH 


• 




• 

SETUP: 


;SET 


UP FILE 






• 


OPEN 


THE FILE FOR INPUT 


01FF 


115C00 




LXI 


D,FCB 


0202 


0E0F 




MVI 


COPENF 


0204 


CD0500 




CALL 


BDOS 






• 


CHECK 


FOR ERRORS 


0207 


FEFF 




CPI 


255 


0209 


C21102 




JNZ 


OPNOK 
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020C 0601 
020E CD9401 



0211 AF 

0212 327C00 
0215 C9 



0216 
0219 
U21C 
021E 
0221 
0224 
0226 



E5D5C5 

115C00 

0E14 

CD0500 

CIDIEI 

FE00 

C8 



0227 FE01 
0229 CAF701 

022C 0602 
022E CD9401 



;OPEN ERROR 



; BAD OPEN 

MVI B r 1 

CALL ERR 

OPNOK: ;OPEN IS OK. 

XRA A 

STA FCBCR 
RET 

DISKR: ;READ DISK FILE RECORD 

PUSH Hi PUSH DI PUSH B 

LXI D,FCB. 

MVI CrREA-DF 

CALL BDOS 

CB'i 0 
RZ 

; MAY BE EOF 

CPI 1 
JZ FINIS 



•check' FOR ERRS 



MVI 
CALL 



B,2 

ERR 



;DISK READ ERROR 



0231 



END 
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The PL/M program which follows implements the CP/M LOAD utility. The 
function is as follows. The user types 

LOAD filename^ 

If filename. HEX exists on the diskette, then the LOAD utility reads the "hex" 
formatted machine code file and produces the file 

filename . COM 

where the COM file contains an absolute memory image of the machine code, 
ready for load and execution in the TPA. If the file does not appear on 
the diskette, the LOAD program types 

SOURCE IS READER 

and reads an Addmaster paper tape reader which contains the hex file. 

The LOAD program is set up to load and run in the TPA, and, upon com- 
pletion, return to the CCP without rebooting the system. Thus, the pro- 
gram is constructed as a single procedure called LOADCOM which takes the 
form 

OFAH : 

LOADCOM: PROCEDURE; 
^ /* LIBRARY PROCEDURES */ 
MONl : ... 

/* END LIBRARY PROCEDURES */ 
MOVE : ... 
GETCHAR: . . . 
PRINTNIB : ... 
PRINTHEX: ... 
PRINTADDR: . . . 
RELOC : ... 
SETMEM: 
READHEX; 
READBYTE : 
READCS: 
MAKEDOUBLE : 
DIAGNOSE : 
^END RELOC; 

DECLARE STACK (16) ADDRESS, SP ADDRESS; 
SP = STACKPTR; STACKPTR = . STACK (LENGTH (STACK) ) ; 

CALL RELOC; 

STACKPTR = SP; 
RETURN 0; 
END LOADCOM; 

EOF 
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The label OF AH at the beginning sets the origin of the compilation to OFAH, 
which causes the first 6 bytes of the compilation to be ignored when loaded 
(i.e., the TPA starts at location lOOH and thus OF AH , . . . , DFFH are deleted 
from the COM file) . In a PL/M compilation, these 6 bytes are used to set up 
the stack pointer and branch around the subroutines in the program. In this 
case, there is only one subroutine, called LOADCOM, which results in the 
following machine memory image for LOAD 

OFAH: LXI SP,plmstack ;SET SP TO DEFAULT STACK 

OFDH: JMP pastsubr ;JUMP AROUND LOADCOM 

lOOH: beginning of LOADCOM procedure 

end of LOADCOM procedure 
RET 

pastsubr : 
EI 
HLT 

Since the machine code between OFAH and OFFH is deleted in the load, 
execution actually begins at the top of LOADCOM. Note, however, that 
the initialization of the SP to the default stack has also been deleted; 
thus, there is a declaration and initialization of an explicit stack and 
stack pointer before the call to RELOC at the end of LOADCOM. This is 
necessary only if we wish to return to the CCP without a reboot operation: 
otherwise the origin of the program is set to lOOH, the declaration of 
LOADCOM as a procedure is not necessary, and termination is accomplished 
by simply executing a 

GO TO OOOOH; 

at the end of the program. Note also that the overhead for a system re- 
boot is not great (approximately 2 seconds) , but can be bothersome for 
system utilities which are used quite often, and do not need the extra 
space. 

The procedures listed in LOADCOM as "library procedures" are a standard 
set of PL/M subroutines which are useful for CP/M interface. The RELOC 
procedure contains several nested subroutines for local functions, and 
actually perfoms the load operation when called from LOADCOM. Control 
initially starts on line 327 where the stackpointer is saved and re- initialized 
to the local stack. The default file control block name is copied to 
another file control block (SFCB) since two files may be open at the same 
time. The program then calls SEARCH to see if the HEX file exists; if not, 
then the high speed reader is used. If the file does exist, it is opened for 
input (if possible) . The filetype COM is moved to the default file control 
block area, and any existing copies of filename.COM files are removed from 
the diskette before creating a new file. The MAKE operation creates a new 
file, and, if successful, RELOC is called to read the HEX file and produce 
the COM file. At the end of processing by RELOC, the COM file is closed 
(line 350) . Note that the HEX file does not need to be closed since it 
was opened for input only. The ^^ata written to a file is not permanently 
recorded until the file is succesiafully closed. 
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Disk input characters are read through the procedure GETCHAR on line 
137. Although the DMA facilities of CP/M could be used here, the GETCHAR 
procedure instead uses the default buffer at location 80H and moves each 
buffer into a vector called SBUFF (source buffer) as it is read. On exit, 
the GETCHAR procedure returns the next input character and updates the 
source buffer pointer (SBP) . 

The SETMEM procedure on line 191 performs the opposite function from 
GETCHAR. The SETMEM procedure maintains a buffer of loaded machine code 
in pure binary form which acts as a "window" on the loaded code. If there 
is an attempt by RELOC to write below this window, then the data is ignored. 
If the data is within the window, then it is placed into MBUFF (memory 
buffer) . If the data is to be placed above this window, then the window 
is moved up to the point where it would include the data address by writing 
the memory image successively (by 128 byte buffers) , and moving the base 
address of the window. Using this technique, the pirogrammer can recover 
from checksum errors on the high-speed reader by stopping the reader, 
rewinding the tape for seme distance, then restarting LOAD (in this case, 
LOADing is resiamed by interrupting with a NOP instruction) . Again, the 
SETMEM procedure uses the default buffer at location BOH to perfom the 
disk output by moving 128 byte segments to 80H through OF.FH before each 
write. 
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0FAH: DECLARE BDOS LITERALLY '0005H'; 
/* TRANSIENT COMMAND LOADER PROGRAM 

COPYRIGHT (C) DIGITAL RESEARCH 
JUNE, 1975 

*/ 

LOADCOM: PROCEDURE BYTE; 

DECLARE FCBA ADDRESS INITIAL ( 5Cri) ; 
DECLARE FCB BASED FCBA (33) BYTE; 

DECLARE BUFFA ADDRESS INITIAL ( 80H) , /* I/O BUFFER ADDR 

BUFFER BASED BUFFA (128) BYTE; 

DECLARE SFCB(33) BYTE, /* SOURCE FILE CONTROL BLOCK * 

BSIZE LITERALLY '1024', 
EOFILE LITERALLY 'lAH', 

S6UFF (BSIZE) BYTE /* SOURCE FILE BUFFER */ 

INITIAL(EOFIL£) , 
RFLAG BYTE, /* READER FLAG */ 

SBP ADDRESS; /* SOURCE FILE BUFFER POINTER 



/* LOADCOM LOADS TRANSIENT COMMAND FILES TO THE DISK F 
' CURRENTLY DEFINED READER PERIPHERAL. THE LOADER PLACE 
CODE INTO A FILE WHICH APPEARS IN THE LOADCOM COMMAND 
/* **************** LIBRARY PROCEDURES FOR DISKIO ******* 



MONl: PROCEDURE (F, A) ; 
DECLARE F BYTE, 
A ADDRESS; 
GO TO BDOS; 
END MONl; 

M0N2: PROCEDURE (F, A) BYTE; 
DECLARE F BYTE, 
A ADDRESS; 
GO TO BDOS; 
END M0N2; 

READRDR: PROCEDURE BYTE; 

/* READ CURRENT READER DEVICE */ 
RETURN MON2(3,0) ; 
END READRDR; 

DECLARE 

TRUE LITERALLY '1', 

FALSE LITERALLY '0', 

FOREVER LITERALLY 'WHILE TRUE', 

CR LITERALLY '13 ' , 
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LF LITERALLY '10', 
WHAT LITERALLY '63'; 

PRINTCHAR: PROCEDURE (CHAR) ; ^3 
DECLARE CHAR BYTE; 
CALL MONl (2,CHAR) ; 
END PRINTCHAR; 

CRLF: PROCEDURE; 

CALL PRINTCHAR (CR) ; 
CALL PRINTCHAR (LF) ; 
END CRLF; 

PRINT: PROCEDURE (A) ; 

DECLARE A ADDRESS; 

/* PRINT THE STRING STARTING AT ADDRESS A UNTIL THE 
NEXT DOLLAR SIGN IS ENCOUNTERED */ 
CALL CRLF; 
CALL MONl (9, A) ; 
END PRINT; 

DECLARE DCNT BYTE; 

INITIALIZE: PROCEDURE; 
CALL MONl (13,0) ; 
END INITIALIZE; 

SELECT: PROCEDURE ( D) ; 
DECLARE D BYTE; 
CALL MONK 14, D) ; 
END SELECT; 

OPEN : PROCEDURE (FCB) ; 

DECLARE FCB ADDRESS; 
DCNT = MON2(15,FCB) ; 
END OPEN; 

CLOSE: PROCEDURE (FCB) ; 

DECLARE FCB ADDRESS; 
DCNT = M0N2 (16 ,FCB) ; 
END CLOSE; 

SEARCH: PROCEDURE ( FCB) ; 
DECLARE FCB ADDRESS; 
DCNT = M0N2 (17,FCB) ; 
END SEARCH; 

SEARCHN: PROCEDURE; 

DCNT = M0N2 (18,0) ; 
END SEARCHN; 

DELETE : PROCEDURE ( FCB ) ; 
DECLARE FCB ADDRESS; 
CALL MONl (19, FCB) ; 
END DELETE; 

DISKREAD: PROCEDURE ( FCB) BYTE; 
DECLARE FCB ADDRESS; 
RETURN M0N2 (20 ,FCB) ; 
END DISKREAD; 
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DISKWRITE: PROCEDURE ( FCB) BYTE; 
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DECLARE FCB ADDRESS ; 
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RETURN M0N2 (21 ,FCB) ; 34 
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END DISKWRITE: 
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2 
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MAKE: PROCEDURE (FCB) ; 
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DECLARE FCB ADDRESS • 
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DCNT = M0N2 (22 ,FCB) ; 
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END MAKE; 
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RENAME: PROCEDURE (FCB) ; 


00123 
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DECLARE FCB ADDRESS; 
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CALL MONl { 23 ;FCB) ; 
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END RENAME; 
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/* ******************* gjqn OF LIBRARY PROCEDURES ********' 


***** * 
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MOVE: PROCEDURE (S ,D,N) ; 
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DECLARE (S,D) ADDRESS, N BYTE, 


00131 


3 


A BASED S BYTE, B BASED D BYTE; 
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DO WHILE (N:=N-1) <> 255; 
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B = A; S=S+1 ; D=D+1 ; 
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END; 


00135 


3 


END MOVE : 
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GETCHAR: PROCEDURE BYTE; 
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/* GET NEXT CHARACTER */ 
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DECLARE I BYTE ; 
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IF RFLAG THEN RETURN READRDR ; 
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IF (SBP := SBP+1) <= LAST(SBUFF) THEN 
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RETURN SBUFF(SBP); 
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/* OTHERWISE READ ANOTHER BUFFER FULL */ 
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DO SBP = 0 TO LAST(SBUFF) BY 128; 
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IF (I: =DISKREAD ( .SFCB) ) = 0 THEN 
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CALL MOVE ( 80H , .SBUFF (SBP) , 80H) ; ELSE 
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DO; IF lOl THEN CALL PRINT(.'DISK READ ER 


ROR$ ' ) ; 
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SBUFF (SBP) = EOFILE; 
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SBP = LAST (SBUFF); 
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END; 
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END; 
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SBP = 0; RETURN SBUFF; 
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END GETCHAR; 
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STACKPOINTER LITERALLY 'STACKPTR': 
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PRINTNIB: PROCEDURE (N ) ; 
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DECLARE N BYTE ; 
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IF N > 9 THEN CALL PRINTCHAR ( N+ ' A '-1 0 ) ; ELSE 
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CALL PRINTCHAR ( N+ ' 0 ' ) ; 
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END PRINTNIB; 
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PRINTHEX: PROCEDURE ( B) ; 
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DECLARE B BYTE; 
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CALL PRINTNIB (SHR ( B , 4) ) : CALL PRINTNIBfB AND 0FH) • 
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END PRINTHEX* 
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PRINTADDR: PROCEDURE (A) ; 
DECLARE A ADDRESS; 

CALL PRINTHEX{HIGH(A) ) ; CALL PRINTHEX ( LOW (A) ) ; 
END PRINTADDR; 
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/* INTEL HEX FORMAT LOADER */ 

RELOC: PROCEDURE; 

DECLARE (RL, CS , RT) BYTE; 
DECLARE 



I^A 




/* 


_1lQAD . ADDRESS. */ „ 


TA 


ADDRESS, 


/* 


TEMP ADDRESS */ 


SA 


ADDRESS , 


/* 


START ADDRESS */ 


FA 


ADDRESS , 


/* 


FINAL ADDRESS */ 


NB 


ADDRESS, 


/* 


NUMBER OF BYTES LOADED */ 


SP 


ADDRESS, 


/* 


STACK POINTER UPON ENTRY TO 



M6UFF(256) BYTE, 

P BYTE, 

L ADDRESS; 

SETMEM: PROCEDURE (B) ; 

/* SET MBUFF TO B AT LOCATION LA MOD LENGTH (MBUFF) 

DECLARE (B,I) BYTE; 

IF LA < L THEN /* MAY BE A RETRY */ RETURN; 

DO WHILE LA > L + LAST (MBUFF); /* WRITE A PARA 

DO I = 0 TO 127; /* COPY INTO BUFFER */ 
BUFFER(I) = MBUFF (LOW (L) ) ; L = L + 1; 
END; 

/* WRITE BUFFER ONTO DISK */ 
P = P + 1; 

IF DISKWRITE (FCBA) <> 0 THEN 

DO; CALL PRINT(.'DISK WRITE ERROR$'); 
HALT ; 

/* RETRY AFTER INTERRUPT NOP */ 

L = L - 128; 

END; 

END; 

MBUFF (LOW (LA) ) = B; 
END SETMEM; 

READHEX: PROCEDURE BYTE; 

/* READ ONE HEX CHARACTER FROM THE INPUT */ 
DECLARE H BYTE; 

IF (H := GETCHAR) - '0' <= 9 THEN RETURN H - '0'; 
IF H - 'A' > 5 THEN GO TO CHARERR; 
RETURN H - 'A' + 10; 
END READHEX; 

READBYTE: PROCEDURE BYTE; 

/* READ TWO HEX DIGITS */ 

RETURN SHL (READHEX, 4) OR READHEX; 

END READBYTE; 

READCS: PROCEDURE BYTE; 

/* READ BYTE WHILE COMPUTING CHECKSUM */ 
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DECLARE B BYTE; 
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4 


CS = CS + (B := READBYTE) ; 
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RETURN B; 
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END RE ADC S; 3<J 
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MAKE$DOUBLE: PROCEDURE ( H , L) ADDRESS; 
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/* CREATE A BOUBLE BYTE VALUE FROM TWO SINGLE BYTE 


S V 
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DECLARE {H,L) BYTE; 
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4 


RETURN SHL{DOUBLE(H) ,8) OR L; 
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END MAKE$DOUBLE; 


00236 


3 




00237 


3 


DIAGNOSE: PROCEDURE; 
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DECLARE M BASED TA BYTE; 
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4 
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NEWLINE : PROCEDURE ; 
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CALL CRLF* CALL PRTNTADDR ^ TA ^ • CALL PRINTChAR ( ' : ' ) 
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CALL PRINTCHAR { ' ') ; 
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END NEWLINE; 
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/* PRINT DIAGNOSTIC INFORMATION AT THE CONSOLE */ 
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CALL PRINT(.'LOAD ADDRESS $'); CALL PRINTADDR (TA) ; 
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CALL PRINT (. 'ERROR ADDRESS $'); CALL PRINTADDR ( LA ) ; 
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CALL PRINT (. 'BYTES READ:$'); CALL NEWLINE; 
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DO WHILE TA < LA; 
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4 


IF (LOW{TA) AND 0FH) = 0 THEN CALL NEWLINE; 
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CALL PRINTHEX(MBUFF(TA-L) ) ; TA=T?^+1 ; 
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CALL PRINTCHAR ( * ') ; 
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END; 
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CALL CRLF; 


0025? 
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HALT ; 
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END DIAGNOSE; 
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/* INITIALIZE */ 
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SA, FA, NB = 0; 
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SP = STACKPOINTER; 
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P = 0; /* PARAGRAPH COUNT */ 
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IF FALSE THEN 
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CHARERR: /* ARRIVE HERE IF NON-HEX DIGIT IS ENCOU 


NTERED 


*/ 
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DO; /* RESTORE STACKPOINTER STACKPOINTER = SP; 


• 


A 
** 
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(ZKUL DIAGNOSE; 
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END; 
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/* READ RECORDS UNTIL :00XXXX IS ENCOUNTERED */ 
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DO FOREVER; 
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/* SCAN THE : */ 
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DO WHILE GETCHAR <> ':'; 
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/* SET CHECK SUM TO ZERO, AND SAVE THE RECORD LENG 



CS = 0; 

/* MAY BE THE END OF TAPE */ 
IF (RL := READCS) = 0 THEN 

GO TO FIN; 
NB = NB + RL; 

TA, LA = MAKE$DOUBLE (READCS, READCS) ; 
IF SA = 0 THEN SA = LA; 



/* READ THE RECORD TYPE (NOT CURRENTLY USED) */ 
RT = READCS; 

/* PROCESS EACH BYTE */ 

DO WHILE (RL := PL - 1) <> 255; 
CALL SETMEM (READCS) ; LA = LA+1 ; 
END; 

IF LA > FA THEN FA = LA - 1 ; 

/* NOW READ CHECKSUM AND COMPARE */ 
IF CS + READBYTE <> 0 THEN 

DO; CALL PRINT (. 'CHECK SUM ERROR 

CALL DIAGNOSE; 
END; 

END; 

FIN: 

/* EMPTY THE BUFFERS */ 
TA = LA; 

DO WHILE L < TA; 

CALL SETMEM(0); LA = LA-Hl ; 

END; 

/* PRINT FINAL STATISTICS */ 

CALL PRINT(. 'FIRST ADDRESS $'); CALL PRINTADDR ( SA) ; 
CALL PRINT (.'LAST ADDRESS $'); CALL PRINTADDR ( FA) ; 
CALL PRINT (. 'BYTES READ $'); CALL PRINTADDR (NB) ; 

CALL PRINT (. 'RECORDS WRITTEN $'); CALL PRINTHEX(P); 
CALL CRLF; 



END RELOC; 



/* ARRIVE HERE FROM THE SYSTEM MONITOR, READY TO READ THE" 



/* SET UP STACKPOINTER IN THE LOCAL AREA */ 
DECLARE STACK (16) ADDRESS, SP ADDRESS; 

SP = STACKPOINTER; STACKPOINTER = .STACK ( LENGTH ( STACK) ) ; 

SBP = LENGTH (SBUFF) ; 

/* SET UP THE SOURCE FILE */ 
CALL MOVE(FCBA, .SFCB,33) ; 
CALL MOVE(. ('HEX',0) ,.SFCB(9) ,4) ; 
CALL SEARCH (.SFCB) ; 
IF (RFLAG := DCNT = 255) THEN 

CALL PRINT (. 'SOURCE IS READER$ ' ) ; ELSE 
DO; CALL PRINT (.' SOURCE IS DISKS'); 
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CALL OPEN(.SFCB) ; 

IF DCNT = 255 THEN CALL PRINT (.' -CANNOT OPEN SOURC 

END; ^ 
CALL CRLF; ^ 

CALL MOVE ( . 'COM' ,FCBA+9 ,3) ; 

/* REMOVE ANY EXISTING FILE BY THIS NAME */ 

CALL DELETE (FCBA) ; 

/* THEN OPEN A. NEW FILE */ 

CALL iViAKE(FCBA) ; FCB(32) = 0? /* CREATE AND SET NEXT RECORD */ 
IF DCNT = 255 THEN CALL PRINT {.'NO MORE DIRECTORY SPACE$ ' 

DO; CALL RELOC ; 
CALL CLOSE (FCBA) ; 

IF DCNT = 255 THEN CALL PRINT (. 'CANNOT CLOSE FILE$ 

END; 
CALL CRLF; 

/* RESTORE STACKPOINTER FOR RETURN */ 
STACKPOINTER = SP ; 
RETURN 0; 
END LOADCOM; 

• 

EOF 



